/****************************************************************************
 * Copyright (C) 2011 Maxim Integrated Products, All Rights Reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL MAXIM INTEGRATED PRODUCTS BE LIABLE FOR ANY CLAIM, DAMAGES
 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 * OTHER DEALINGS IN THE SOFTWARE.
 *
 * Except as contained in this notice, the name of Maxim Integrated Products
 * shall not be used except as stated in the Maxim Integrated Products
 * Branding Policy.
 *
 * The mere transfer of this software does not imply any licenses
 * of trade secrets, proprietary technology, copyrights, patents,
 * trademarks, maskwork rights, or any other form of intellectual
 * property whatsoever. Maxim Integrated Products retains all ownership rights.
 *
 *     Description: MAXQ Wake-Up Timer Driver
 *             $Id: maxq_wut.h 1625 2011-07-01 17:49:20Z jbrodt $
 *
 ********************************************************************************
 */

/** 
* \file
* \brief    Driver for configuring and operating the wake-up timer.
* \details  This file defines the driver API including definitions, data types
*           and function prototypes.
*/
#ifndef _MAXQ_WUT_H_
#define _MAXQ_WUT_H_

#include "maxq_config.h"


/***** Definitions *****/

// Register bit masks
/// \cond
#define WTE_MASK    0x01
#define WTF_MASK    0x02
/// \endcond

/// \brief Starts the wake-up timer
#define wut_start()       WUTC|=WTE_MASK

/// Stops the wake-up timer
#define wut_stop()        WUTC&=~WTE_MASK

/// Restarts the wake-up timer
#define wut_restart()     wut_stop();wut_start()

/**
*   \brief    Checks if a wake up timer interrupt has occurred
*   \returns  #TRUE if an interrupt has occurred, #FALSE otherwise
*/
#define wut_int_check()   (!!(WUTC&WTF_MASK))

/// Clears the wake-up timer interrupt flag
#define wut_int_clear()   wut_stop()


/*******Function Prototypes********/
 
/**
*   \brief    Configures the wake-up time
*   \param    ms  Number of milliseconds. Valid range is 1 to 5460 ms.
*   \returns  #MAXQ_SUCCESS if successful, #MAXQ_FAILURE otherwise
*/
int wut_set_time(uint16_t ms);

/**
*   \brief    Calibrates the wake-up timer count value for more accurate wake-up
*             timing.
*   \details  Measures the frequency of the nano-ring oscillator using the
*             external crystal and Timer 1-0. The nano-ring oscillator has a
*             relatively wide frequency variation (see datasheet). The
*             measured frequency is then used by wut_set_time() to initialize
*             the wake-up timer with a more accurate count value.
*   \details  This function should take between 1 and 5 ms to execute, depending
*             on the actual nano-ring frequency.
*   \details  Execution of this function is not required if accuracy of the
*             wake-up time is not critical. In this case, wut_set_time() will
*             use the typical nano-ring frequency value as specified in the
*             product datasheet.
*   \details  This function only needs to be called once per reset cycle to
*             compensate for process variation. To compensate for temperature
*             and voltage variation, this function should be called at a rate
*             determined by the characterstics of the application.
*   \note     This function requires Timer 1-0. If timer 1-0 is currently in
*             use, this function returns immediately without affect.
*   \returns  #MAXQ_SUCCESS if successful, #MAXQ_FAILURE otherwise
*/
int wut_calibrate(void);

#endif  /*_MAXQ_WUT_H_*/

